Home Proxy Menu Search Engine

geminiprotocol.net geminiprotocol.net/docs/gemtext-specification.gmi

Version 0.24.1

This document is placed in the public domain under the following terms:

This document specifies the "gemtext" hypertext format. Gemtext is intended to serve as the "native" response format of the Gemini file transfer protocol, in the same way that HTML is the native response format of HTTP [RFC7230], although it can be used for any other purpose for which it is suitable. Gemtext is served via Gemini using the as-yet unregistered MIME type text/gemini.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP14].

Gemtext is specified here in its so-called "canonical form" and, since text/gemini is a subtype of MIME type "text", line breaks are therefore represented by the sequence CRLF. Note however that the Gemini network protocol specification allows any subtype of "text" to be transmitted with line breaks represented by LF alone.

Gemtext is designed to support simple electronic documents which can link to other online resources and which can be displayed in a manner conducive to easy and pleasant reading on devices with diverse display shapes and sizes. This provides an improved user experience over plain text which is "hard wrapped" to a fixed number of characters (which may be substantially more or less than can fit on a client's display), and where users must manually copy URLs out of the document and into their user agent's interface.

The format is designed to be both as simple to write by hand and as simple to parse as practical. The essential structure of a gemtext document is flat, not hierarchical, and a document can be parsed and rendered correctly in a single top-to-bottom pass.

The format is explicitly NOT intended to facilitate precise and replicable control by document authors over how the document is displayed. Styling is under the exclusive control of the rendering user agent.

As a subtype of the top-level media type "text", "text/gemini" inherits the "charset" parameter defined in [RFC2046]. However, the default value of "charset" is "UTF-8" for "text" content transferred via Gemini.

A single additional parameter

specific to the "text/gemini"

Valid values for the "lang" parameter are comma-separated lists of one or more language tags as defined in [BCP47]. Note that if multiple tags (and hence a comma) are used, the whole value MUST be enclosed in quotation marks (see [RFC2045], section 5.1 "Syntax of the Content-Type Header Field"). For example:

* 'text/gemini; lang=en' Denotes a text/gemini document written in English

* 'text/gemini; lang=fr' Denotes a text/gemini document written in French

* 'text/gemini; lang="en,fr"' Denotes a text/gemini document written in a mixture of English and French

* 'text/gemini; lang=de-CH' Denotes a text/gemini document written in Swiss German

* 'text/gemini; lang=sr-Cyrl' Denotes a text/gemini document written in Serbian using the Cyrillic script

* 'text/gemini; lang=zh-Hans-CN' Denotes a text/gemini document written in Chinese using the Simplified script as used in mainland China

Parameters other than "charset" and "lang" are undefined and clients MUST ignore any such paramters.

Gemtext is a line-oriented format.

A document consists of one or more

The six line types are:

* Text lines

* Link lines

* Heading lines

* List items

* Quote lines

* Preformat toggle lines

To be compliant with this specification, software which parses and displays gemtext documents MUST handle text lines, link lines and preformat toggle lines as described below. These are considered the "core" line types.

Software MAY additionally handle heading lines, list items and quote lines as described below to improve user experience. Software which does not handle these lines as described MUST handle them as if they were text lines.

A compliant gemtext parser must

maintain a single bit of internal

Text lines are the "default" line type, in the sense that all other line types are recognised by virtue of beginning with a specific identifying prefix. Any line which does not begin with such a prefix is a text line. In a typical gemtext document, the majority of the lines will be text lines.

Text lines have no special

semantics and should be presented

Text lines which are longer than can fit on a client's display device SHOULD be "wrapped" to fit, i.e. long lines should be split (ideally at whitespace or at hyphens) into multiple consecutive lines of a device-appropriate width. This wrapping is applied to each line of text independently. However, multiple consecutive text lines which are each shorter than the client's display device MUST NOT be combined into fewer, longer lines. Each individual lines in a Gemtext document is a stand-alone entity.

Empty lines, i.e. lines consisting exclusively of CRLF, are valid instances of text lines and have no special meaning. They should be rendered individually as vertical blank space each time they occur. Multiple consecutive empty lines should NOT be collapsed into fewer empty lines and should be rendered as a quantity of vertical blank space proportional to the number of lines.

All lines beginning with the two characters "=>" are link lines. Link lines allow Gemtext documents to link to other online resources, including other Gemtext documents. Link lines have the following syntax:

`F089`[LINK NAME>}`:/page/rgproxy.mu`resultat=geminiprotocol.net/docs/[<whitespace>]<URL>[<whitespace><USER-FRIENDLY|backurl=geminiprotocol.net/docs/gemtext-specification.gmi]`f``

where:

* <whitespace> is any non-zero number of consecutive spaces or tabs

* Square brackets indicate that the enclosed content is optional.

* <URL> is a URL, which may be absolute or relative.

All the following examples are valid link lines:

`=`F19f`[gemini://example.org/`:/page/rgproxy.mu`resultat=example.org/|backurl=geminiprotocol.net/docs/gemtext-specification.gmi]`f``

`=`F19f`[An example link`:/page/rgproxy.mu`resultat=example.org/|backurl=geminiprotocol.net/docs/gemtext-specification.gmi]`f``

`=`F19f`[Another example link at the same host`:/page/rgproxy.mu`resultat=example.org/foo|backurl=geminiprotocol.net/docs/gemtext-specification.gmi]`f``

`F089`[A relative link`:/page/rgproxy.mu`resultat=geminiprotocol.net/docs/foo/bar/baz.txt|backurl=geminiprotocol.net/docs/gemtext-specification.gmi]`f``

`F190`[gopher://example.org:70/1`:/page/gopher.mu`resultat=example.org:70/1|backurl=gemini://geminiprotocol.net/docs/gemtext-specification.gmi]`f``

URLs in link lines MUST have reserved characters and spaces percent-encoded as per RFC 3986.

Clients can present links to users in whatever fashion the client author wishes, however clients MUST NOT automatically make any network connections as part of displaying links.

Any line whose first three characters are "'''" (i.e. three consecutive back ticks with no leading whitespace) are preformatted toggle lines. These lines should NOT be included in the rendered output shown to the user. Instead, they switch the parser out of "normal mode" and into "pre-formatted" mode.

Any text following the leading

"'''" of a preformat toggle line

Lines beginning with "#" are heading lines. Heading lines consist of one, two or three consecutive "#" characters, followed by optional whitespace, followed by heading text. The number of # characters indicates the "level" of heading; # lines are headings, ## lines are sub-headings and ### lines are sub-sub headings.

The text of a heading text should

be presented to the user, and

Lines beginning with "* " are list items. This line type exists purely for stylistic reasons. The * may be replaced in advanced clients by a bullet symbol. Any text after the "* " should be presented to the user as if it were a text line, i.e. wrapped to fit the viewport and formatted "nicely". Advanced clients can take the space of the bullet symbol into account when wrapping long list items to ensure that all lines of text corresponding to the item are offset an equal distance from the edge of the screen.

Lines beginning with ">" are quote lines. This line type exists so that advanced clients may use distinct styling to convey to readers the important semantic information that certain text is being quoted from an external source. For example, when wrapping long lines to the viewport, each resultant line may have a ">" symbol placed at the front.

Any line which does not begin with

the three characters "'''" is a

Any line whose first three characters are "'''" (i.e. three consecutive back ticks with no leading whitespace) are preformatted toggle lines. These lines should NOT be included in the rendered output shown to the user. Instead, they switch the parser out of "pre-formatted mode" and into "normal mode".

Any text following the leading "'''" of a preformat toggle line MUST be ignored by clients.

The following is an augmented BNF specification for a UTF-8 encoded gemtext document.

gemtext-document = 1*gemtext-line

gemtext-line = text-line / link-line / preformat-toggle

gemtext-line =/ heading / list-item / quote-line

link-line = "=>" *WSP URI-reference [1*WSP 1*(SP / VCHAR)] *WSP CRLF

heading = ( "#" / "##" / "###" ) text-line

list-item = "*" SP text-line

quote-line = ">" text-line

preformat-toggle = "'''" text-line

text-line = *(WSP / VCHAR) CRLF

VCHAR =/ UTF8-2v / UTF8-3 / UTF8-4

UTF8-2v = %xC2 %xA0-BF UTF8-tail ; no C1 control set

/ %xC3-DF UTF8-tail

; URI-reference from [STD66]

;

; CRLF from [STD68]

; SP from [STD68]

; WSP from [STD68]

; VCHAR from [STD68]

* [BCP14] Key words for use in RFCs to Indicate Requirement Levels

* [BCP47] Tags for Identifying Languages

* [RFC2045] Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies

* [RFC2046] Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types

* [STD63] UTF-8, a transformation format of ISO 10646

* [STD66] Uniform Resource Identifier (URI): Generic Syntax

* [STD68] Augmented BNF for Syntax Specifications: ABNF

* [RFC1436] The Internet Gopher Protocol

* [RFC7230] Hypertext Transfer Protocol

you're on geminiprotocol.net/docs/gemtext-specification.gmi